home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / c / gcc263-utildoc.lha / gnu / man / man1 / tar.1 < prev    next >
Encoding:
Text File  |  1994-12-19  |  13.9 KB  |  288 lines
  1.  
  2.  
  3.  tar(C)                        06 January 1993                         tar(C)
  4.  
  5.  _N_a_m_e
  6.  
  7.     tar - archive files
  8.  
  9.  _S_y_n_t_a_x
  10.  
  11.     ttaarr [ _kk_ee_yy ] [ _ff_ii_ll_ee_ss ]
  12.  
  13.  _D_e_s_c_r_i_p_t_i_o_n
  14.  
  15.     The ttaarr command saves and restores files to and from an archive medium,
  16.     which is typically a floppy disk or tape, or a standard file.  Its
  17.     actions are controlled by the _kk_ee_yy argument.  The _kk_ee_yy is a string of char-
  18.     acters containing at most one function letter and possibly one or more
  19.     function modifiers.  Valid function letters are rr, xx, tt, uu, cc, and ee.
  20.     Other arguments to the command are _ff_ii_ll_ee_ss (or directory names) specifying
  21.     which files are to be backed up or restored.  In all cases, a directory
  22.     name refers to the files and (recursively) the subdirectories of that
  23.     directory.  The rr and uu options cannot be used with tape devices.
  24.  
  25.     The function portion of the key is specified by one of the following
  26.     letters:
  27.  
  28.     rr         The named _ff_ii_ll_ee_ss are written to the end of an existing archive.
  29.  
  30.     xx         The named _ff_ii_ll_ee_ss are extracted from the archive.  If a named
  31.               file matches a directory whose contents had been written onto
  32.               the archive, this directory is (recursively) extracted.  The
  33.               owner, modification time, and mode are restored (if possible).
  34.               If no _ff_ii_ll_ee_ss argument is given, the entire contents of the
  35.               archive are extracted.  Note that if several files with the
  36.               same name are on the archive, the last one overwrites all ear-
  37.               lier ones.
  38.  
  39.     tt         The names of the specified files are listed each time that they
  40.               occur on the archive.  If no _ff_ii_ll_ee_ss argument is given, all the
  41.               names on the archive are listed.
  42.  
  43.     uu         The named _ff_ii_ll_ee_ss are added to the archive if they are not
  44.               already there, or if they have been modified since last written
  45.               on that archive.
  46.  
  47.     cc         Creates a new archive; writing begins at the beginning of the
  48.               archive, instead of after the last file.
  49.  
  50.     The following characters may be used in addition to the letter that
  51.     selects the desired function:
  52.  
  53.     00,,......,,99999999
  54.               This numeric key selects the device on which the archive is
  55.               mounted. The available numeric keys are defined in the file
  56.               /_e_t_c/_d_e_f_a_u_l_t/_t_a_r. A list of archive devices and their corre-
  57.               sponding numeric keys can be displayed by entering ttaarr without
  58.               any arguments. The ff option is used to specify an archive de-
  59.               vice which is not in /_e_t_c/_d_e_f_a_u_l_t/_t_a_r.
  60.  
  61.     vv         Normally, ttaarr does its work silently.  The vv (verbose) option
  62.               causes it to display the name of each file it treats, preceded
  63.               by the function letter.  With the tt function, vv gives more in-
  64.               formation about the archive entries than just the name.
  65.  
  66.     ww         Causes ttaarr to display the action to be taken, followed by the
  67.               name of the file, and then wait for the user's confirmation.
  68.               If a word beginning with ``y'' is given, the action is per-
  69.               formed.  Any other input means ``no''.
  70.  
  71.     ff         Causes ttaarr to use the next argument as the name of the archive
  72.               instead of the default device listed in /_e_t_c/_d_e_f_a_u_l_t/_t_a_r.  If
  73.               the name of the file is a dash (-), ttaarr writes to the standard
  74.               output or reads from the standard input, whichever is appropri-
  75.               ate.  Thus, ttaarr can be used as the head or tail of a pipeline.
  76.               ttaarr can also be used to move hierarchies with the command:
  77.  
  78.                  ccdd ffrroommddiirr;; ttaarr ccff -- .. || ((ccdd ttooddiirr;; ttaarr xxff --))
  79.  
  80.     bb         Causes ttaarr to use the next argument as the blocking factor for
  81.               archive records.  The default is 1, the maximum is 20.  This
  82.               option should only be used with raw magnetic tape archives (see
  83.               ff above).  The block size is determined automatically when
  84.               reading tapes (key letters xx and tt).
  85.  
  86.     FF         Causes ttaarr to use the next argument as the name of a file from
  87.               which succeeding arguments are taken.
  88.  
  89.     ll         Tells ttaarr to display an error message if it cannot resolve all
  90.               of the links to the files being backed up.  If ll is not speci-
  91.               fied, no error messages are displayed.
  92.  
  93.     mm         Tells ttaarr not to restore the modification times.  The modifica-
  94.               tion time of the file is the time of extraction.
  95.  
  96.     kk         Causes ttaarr to use the next argument as the size of an archive
  97.               volume in kilobytes (K).  The minimum value allowed is 250.
  98.               Very large files are split into ``extents'' across volumes.
  99.               When restoring from a multi-volume archive, ttaarr only prompts
  100.               for a new volume if a split file has been partially restored.
  101.               To override the value of kk in the default file, specify kk as 0
  102.               on the command line.
  103.  
  104.     ee         Prevents files from being split across volumes (tapes or floppy
  105.               disks).  If there is not enough room on the present volume for
  106.               a given file, ttaarr prompts for a new volume.  This is only valid
  107.               when the kk option is also specified on the command line.
  108.  
  109.     nn         Indicates the archive device is not a magnetic tape. The kk
  110.               option implies this. Listing and extracting the contents of an
  111.               archive are faster because ttaarr can seek over files it wishes to
  112.               skip.  Sizes are printed in kilobytes instead of tape blocks.
  113.  
  114.     pp         Indicates that files are extracted using their original permis-
  115.               sions.  It is possible that a non-super user may be unable to
  116.               extract files because of the permissions associated with the
  117.               files or directories being extracted.
  118.  
  119.     AA         Suppresses absolute filenames. Any leading ``/'' characters are
  120.               removed from filenames.  During extraction arguments given
  121.               should match the relative (rather than the absolute) pathnames.
  122.               With the cc, rr, and uu options, the AA option can be used to inhi-
  123.               bit putting leading slashes in the archive headers.
  124.  
  125.     qq         During extraction causes ttaarr to exit immediately after each
  126.               file on the command line has been extracted, rather than con-
  127.               tinuing to look for additional files of the same name.
  128.  
  129.     LL         Follow symbolic links. By default, symbolic links are not fol-
  130.               lowed; when ttaarr encounters a symbolic link, it issues a warning
  131.               message, skips over the link, and continues with the rest of
  132.               the files.
  133.  
  134.     TT         Truncates filenames of greater than 14 characters on extrac-
  135.               tion.  This is used for extracting files from EAFS-type file-
  136.               systems that support long filenames (up to 255 characters long)
  137.               to AFS-type filesystems that support maximum 14-character
  138.               filenames.
  139.  
  140.     If no archive device is specified, either by using a numeric key or the ff
  141.     option, ttaarr looks for a line in the file /_e_t_c/_d_e_f_a_u_l_t/_t_a_r beginning with
  142.     the string aarrcchhiivvee==.  Following this string are 4 fields, separated by
  143.     spaces, which contain values for the device name, blocking factor, volume
  144.     size, and device type.  The blocking factor is the size in kilobytes of
  145.     each block on the archive medium. The volume size entry should be modi-
  146.     fied to reflect the size in kilobytes of the archive volume used. Note
  147.     that a volume size of `0' indicates infinite volume length. The device
  148.     type is set to yy for tape devices; otherwise, it is set to nn.
  149.  
  150.     For example, the following is the default device entry from
  151.     /_e_t_c/_d_e_f_a_u_l_t/_t_a_r:
  152.  
  153.        archive=/dev/fd096ds15 10 1200 n
  154.  
  155.     This indicates that the default device is a floppy disk drive with a
  156.     blocking factor of 10K and a volume size of 1.2 megabytes (1.2M).  Any
  157.     default value may be overridden using the bb and kk options.
  158.  
  159.     When a numeric key (#, in the range 0-9999) is specified, the corre-
  160.     sponding device attributes are read from the line beginning with
  161.     aarrcchhiivvee##== in the file /_e_t_c/_d_e_f_a_u_l_t/_t_a_r. The remainder of the line has the
  162.     same format as for the default archive device.
  163.  
  164.     The default file /_e_t_c/_d_e_f_a_u_l_t/_t_a_r must exist if a device is not specified
  165.     on the command line using the ff option.
  166.  
  167.     A critical consideration when creating a tar volume involves the use of
  168.     absolute or relative pathnames.  Consider the following ttaarr command exam-
  169.     ples, as executed from the directory /_u/_t_a_r_g_e_t:
  170.  
  171.        ttaarr ccvv //uu//ttaarrggeett//aarrrrooww
  172.        ttaarr ccvv aarrrrooww
  173.  
  174.     The first command creates a tar volume with the absolute pathname:
  175.     /_u/_t_a_r_g_e_t/_a_r_r_o_w.  The second yields a tar volume with a relative path-
  176.     name: ./_a_r_r_o_w. (The ./ is implicit and shown here as an example; ./
  177.     should not be specified when retrieving the file from the archive.)  When
  178.     restored, the first example results in the file _a_r_r_o_w being written to
  179.     the directory /_u/_t_a_r_g_e_t (if it exists and you have write permission) no
  180.     matter what your working directory.  The second example simply writes the
  181.     file _a_r_r_o_w to your present working directory.
  182.  
  183.     Absolute pathnames specify the location of a file in relation to the root
  184.     directory (/); relative pathnames are relative to the current directory.
  185.     This must be taken into account when making a tar tape or disk.  Backup
  186.     volumes use absolute pathnames so that they can be restored to the proper
  187.     directory.  Use relative pathnames when creating a tar volume where abso-
  188.     lute pathnames are unnecessary.
  189.  
  190.  _E_x_a_m_p_l_e_s
  191.  
  192.     If the name of a floppy disk device is /_d_e_v/_f_d_1, then a tar format file
  193.     can be created on this device by entering:
  194.  
  195.        aassssiiggnn //ddeevv//ffdd
  196.        ttaarr ccvvffkk //ddeevv//ffdd11 336600 _ff_ii_ll_ee_ss
  197.  
  198.     where _ff_ii_ll_ee_ss are the names of files you want archived and 360 is the capa-
  199.     city of the floppy disk in kilobytes.  Note that arguments to key letters
  200.     are given in the same order as the key letters themselves, thus the ffkk
  201.     key letters have corresponding arguments /_d_e_v/_f_d_1 and 360.  If you
  202.     aassssiiggnn(C) the disk at the beginning, remember to ddeeaassssiiggnn it when you
  203.     have finished.
  204.  
  205.     To display a listing of the archive, enter:
  206.  
  207.        ttaarr ttvvff //ddeevv//ffdd11
  208.  
  209.     At some later time you may want to extract the files from the archive
  210.     floppy.  You can do this by entering:
  211.  
  212.        ttaarr xxvvff //ddeevv//ffdd11
  213.  
  214.     The above command extracts all files from the archive, using the exact
  215.     same pathnames as used when the archive was created. Because of this
  216.     behavior, it is normally best to save archive files with relative path-
  217.     names rather than absolute ones, since directory permissions may not let
  218.     you read the files into the absolute directories specified.  (See the AA
  219.     flag under ``Options''.)
  220.  
  221.     In the above examples, the vv verbose option is used simply to confirm the
  222.     reading or writing of archive files on the screen. Also, a normal file
  223.     could be substituted for the floppy device /_d_e_v/_f_d_1 shown in the exam-
  224.     ples.
  225.  
  226.     If the default device were to be used for the above examples, the corre-
  227.     sponding ttaarr commands would be:
  228.  
  229.        ttaarr ccvvkk 336600 _ff_ii_ll_ee_ss
  230.        ttaarr ttvv
  231.        ttaarr xxvv
  232.  
  233.     The ttaarr commands for the device corresponding to 5 in the device table
  234.     would be:
  235.  
  236.        ttaarr ccvv55kk 336600 _ff_ii_ll_ee_ss
  237.        ttaarr ttvv55
  238.        ttaarr xxvv55
  239.  
  240.  _F_i_l_e_s
  241.  
  242.     /_e_t_c/_d_e_f_a_u_l_t/_t_a_r
  243.                    Default devices, blocking and volume sizes, device type
  244.     /_t_m_p/_t_a_r*
  245.  
  246.  _S_e_e _a_l_s_o
  247.  
  248.     aassssiiggnn(C) and ttaarr(F).
  249.  
  250.  _D_i_a_g_n_o_s_t_i_c_s
  251.  
  252.     Displays an error message about bad key characters and archive read/write
  253.     errors.
  254.  
  255.     Displays an error message if not enough memory is available to hold the
  256.     link tables.
  257.  
  258.  _N_o_t_e_s
  259.  
  260.     There is no way to ask for the _nnth occurrence of a file.
  261.  
  262.     ttaarr does not verify the selected media type.
  263.  
  264.     The uu option can be slow.
  265.  
  266.     The limit on pathname length is 100 characters.
  267.  
  268.     When archiving a directory that contains subdirectories, ttaarr will only
  269.     access those subdirectories that are within 17 levels of nesting.  Sub-
  270.     directories at higher levels will be ignored after ttaarr displays an error
  271.     message.
  272.  
  273.     When using ttaarr with a raw device, specify the block size with the bb
  274.     option as a multiple of 512 bytes.  For example, to use a 9K block size,
  275.     enter:
  276.  
  277.        ttaarr ccvvffbb //ddeevv//rrffdd00 1188 _ff_ii_ll_ee
  278.  
  279.     Do not enter:
  280.  
  281.        ttaarr xxffFF -- --
  282.  
  283.     This would imply taking two things from the standard input at the same
  284.     time.
  285.  
  286.     Use error-free floppy disks for best results with ttaarr.
  287.  
  288.